// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef BASE_FEATURE_LIST_H_
#define BASE_FEATURE_LIST_H_

#include <map>
#include <memory>
#include <string>
#include <vector>

#include "base/base_export.h"
#include "base/gtest_prod_util.h"
#include "base/macros.h"
#include "base/metrics/persistent_memory_allocator.h"
#include "base/strings/string_piece.h"
#include "base/synchronization/lock.h"

namespace base {

class FieldTrial;

// Specifies whether a given feature is enabled or disabled by default.
enum FeatureState {
    FEATURE_DISABLED_BY_DEFAULT,
    FEATURE_ENABLED_BY_DEFAULT,
};

// The Feature struct is used to define the default state for a feature. See
// comment below for more details. There must only ever be one struct instance
// for a given feature name - generally defined as a constant global variable or
// file static.
struct BASE_EXPORT Feature {
    constexpr Feature(const char* name, FeatureState default_state)
        : name(name)
        , default_state(default_state)
    {
    }
    // The name of the feature. This should be unique to each feature and is used
    // for enabling/disabling features via command line flags and experiments.
    const char* const name;

    // The default state (i.e. enabled or disabled) for this feature.
    const FeatureState default_state;
};

// The FeatureList class is used to determine whether a given feature is on or
// off. It provides an authoritative answer, taking into account command-line
// overrides and experimental control.
//
// The basic use case is for any feature that can be toggled (e.g. through
// command-line or an experiment) to have a defined Feature struct, e.g.:
//
//   const base::Feature kMyGreatFeature {
//     "MyGreatFeature", base::FEATURE_ENABLED_BY_DEFAULT
//   };
//
// Then, client code that wishes to query the state of the feature would check:
//
//   if (base::FeatureList::IsEnabled(kMyGreatFeature)) {
//     // Feature code goes here.
//   }
//
// Behind the scenes, the above call would take into account any command-line
// flags to enable or disable the feature, any experiments that may control it
// and finally its default state (in that order of priority), to determine
// whether the feature is on.
//
// Features can be explicitly forced on or off by specifying a list of comma-
// separated feature names via the following command-line flags:
//
//   --enable-features=Feature5,Feature7
//   --disable-features=Feature1,Feature2,Feature3
//
// After initialization (which should be done single-threaded), the FeatureList
// API is thread safe.
//
// Note: This class is a singleton, but does not use base/memory/singleton.h in
// order to have control over its initialization sequence. Specifically, the
// intended use is to create an instance of this class and fully initialize it,
// before setting it as the singleton for a process, via SetInstance().
class BASE_EXPORT FeatureList {
public:
    FeatureList();
    ~FeatureList();

    // Initializes feature overrides via command-line flags |enable_features| and
    // |disable_features|, each of which is a comma-separated list of features to
    // enable or disable, respectively. If a feature appears on both lists, then
    // it will be disabled. If a list entry has the format "FeatureName<TrialName"
    // then this initialization will also associate the feature state override
    // with the named field trial, if it exists. If a feature name is prefixed
    // with the '*' character, it will be created with OVERRIDE_USE_DEFAULT -
    // which is useful for associating with a trial while using the default state.
    // Must only be invoked during the initialization phase (before
    // FinalizeInitialization() has been called).
    void InitializeFromCommandLine(const std::string& enable_features,
        const std::string& disable_features);

    // Initializes feature overrides through the field trial allocator, which
    // we're using to store the feature names, their override state, and the name
    // of the associated field trial.
    void InitializeFromSharedMemory(PersistentMemoryAllocator* allocator);

    // Specifies whether a feature override enables or disables the feature.
    enum OverrideState {
        OVERRIDE_USE_DEFAULT,
        OVERRIDE_DISABLE_FEATURE,
        OVERRIDE_ENABLE_FEATURE,
    };

    // Returns true if the state of |feature_name| has been overridden via
    // |InitializeFromCommandLine()|.
    bool IsFeatureOverriddenFromCommandLine(const std::string& feature_name,
        OverrideState state) const;

    // Associates a field trial for reporting purposes corresponding to the
    // command-line setting the feature state to |for_overridden_state|. The trial
    // will be activated when the state of the feature is first queried. This
    // should be called during registration, after InitializeFromCommandLine() has
    // been called but before the instance is registered via SetInstance().
    void AssociateReportingFieldTrial(const std::string& feature_name,
        OverrideState for_overridden_state,
        FieldTrial* field_trial);

    // Registers a field trial to override the enabled state of the specified
    // feature to |override_state|. Command-line overrides still take precedence
    // over field trials, so this will have no effect if the feature is being
    // overridden from the command-line. The associated field trial will be
    // activated when the feature state for this feature is queried. This should
    // be called during registration, after InitializeFromCommandLine() has been
    // called but before the instance is registered via SetInstance().
    void RegisterFieldTrialOverride(const std::string& feature_name,
        OverrideState override_state,
        FieldTrial* field_trial);

    // Loops through feature overrides and serializes them all into |allocator|.
    void AddFeaturesToAllocator(PersistentMemoryAllocator* allocator);

    // Returns comma-separated lists of feature names (in the same format that is
    // accepted by InitializeFromCommandLine()) corresponding to features that
    // have been overridden - either through command-line or via FieldTrials. For
    // those features that have an associated FieldTrial, the output entry will be
    // of the format "FeatureName<TrialName", where "TrialName" is the name of the
    // FieldTrial. Features that have overrides with OVERRIDE_USE_DEFAULT will be
    // added to |enable_overrides| with a '*' character prefix. Must be called
    // only after the instance has been initialized and registered.
    void GetFeatureOverrides(std::string* enable_overrides,
        std::string* disable_overrides);

    // Returns whether the given |feature| is enabled. Must only be called after
    // the singleton instance has been registered via SetInstance(). Additionally,
    // a feature with a given name must only have a single corresponding Feature
    // struct, which is checked in builds with DCHECKs enabled.
    static bool IsEnabled(const Feature& feature);

    // Returns the field trial associated with the given |feature|. Must only be
    // called after the singleton instance has been registered via SetInstance().
    static FieldTrial* GetFieldTrial(const Feature& feature);

    // Splits a comma-separated string containing feature names into a vector.
    static std::vector<std::string> SplitFeatureListString(
        const std::string& input);

    // Initializes and sets an instance of FeatureList with feature overrides via
    // command-line flags |enable_features| and |disable_features| if one has not
    // already been set from command-line flags. Returns true if an instance did
    // not previously exist. See InitializeFromCommandLine() for more details
    // about |enable_features| and |disable_features| parameters.
    static bool InitializeInstance(const std::string& enable_features,
        const std::string& disable_features);

    // Returns the singleton instance of FeatureList. Will return null until an
    // instance is registered via SetInstance().
    static FeatureList* GetInstance();

    // Registers the given |instance| to be the singleton feature list for this
    // process. This should only be called once and |instance| must not be null.
    // Note: If you are considering using this for the purposes of testing, take
    // a look at using base/test/scoped_feature_list.h instead.
    static void SetInstance(std::unique_ptr<FeatureList> instance);

    // Clears the previously-registered singleton instance for tests and returns
    // the old instance.
    // Note: Most tests should never call this directly. Instead consider using
    // base::test::ScopedFeatureList.
    static std::unique_ptr<FeatureList> ClearInstanceForTesting();

    // Sets a given (initialized) |instance| to be the singleton feature list,
    // for testing. Existing instance must be null. This is primarily intended
    // to support base::test::ScopedFeatureList helper class.
    static void RestoreInstanceForTesting(std::unique_ptr<FeatureList> instance);

private:
    FRIEND_TEST_ALL_PREFIXES(FeatureListTest, CheckFeatureIdentity);
    FRIEND_TEST_ALL_PREFIXES(FeatureListTest,
        StoreAndRetrieveFeaturesFromSharedMemory);
    FRIEND_TEST_ALL_PREFIXES(FeatureListTest,
        StoreAndRetrieveAssociatedFeaturesFromSharedMemory);

    struct OverrideEntry {
        // The overridden enable (on/off) state of the feature.
        const OverrideState overridden_state;

        // An optional associated field trial, which will be activated when the
        // state of the feature is queried for the first time. Weak pointer to the
        // FieldTrial object that is owned by the FieldTrialList singleton.
        base::FieldTrial* field_trial;

        // Specifies whether the feature's state is overridden by |field_trial|.
        // If it's not, and |field_trial| is not null, it means it is simply an
        // associated field trial for reporting purposes (and |overridden_state|
        // came from the command-line).
        const bool overridden_by_field_trial;

        // TODO(asvitkine): Expand this as more support is added.

        // Constructs an OverrideEntry for the given |overridden_state|. If
        // |field_trial| is not null, it implies that |overridden_state| comes from
        // the trial, so |overridden_by_field_trial| will be set to true.
        OverrideEntry(OverrideState overridden_state, FieldTrial* field_trial);
    };

    // Finalizes the initialization state of the FeatureList, so that no further
    // overrides can be registered. This is called by SetInstance() on the
    // singleton feature list that is being registered.
    void FinalizeInitialization();

    // Returns whether the given |feature| is enabled. This is invoked by the
    // public FeatureList::IsEnabled() static function on the global singleton.
    // Requires the FeatureList to have already been fully initialized.
    bool IsFeatureEnabled(const Feature& feature);

    // Returns the field trial associated with the given |feature|. This is
    // invoked by the public FeatureList::GetFieldTrial() static function on the
    // global singleton. Requires the FeatureList to have already been fully
    // initialized.
    base::FieldTrial* GetAssociatedFieldTrial(const Feature& feature);

    // For each feature name in comma-separated list of strings |feature_list|,
    // registers an override with the specified |overridden_state|. Also, will
    // associate an optional named field trial if the entry is of the format
    // "FeatureName<TrialName".
    void RegisterOverridesFromCommandLine(const std::string& feature_list,
        OverrideState overridden_state);

    // Registers an override for feature |feature_name|. The override specifies
    // whether the feature should be on or off (via |overridden_state|), which
    // will take precedence over the feature's default state. If |field_trial| is
    // not null, registers the specified field trial object to be associated with
    // the feature, which will activate the field trial when the feature state is
    // queried. If an override is already registered for the given feature, it
    // will not be changed.
    void RegisterOverride(StringPiece feature_name,
        OverrideState overridden_state,
        FieldTrial* field_trial);

    // Verifies that there's only a single definition of a Feature struct for a
    // given feature name. Keeps track of the first seen Feature struct for each
    // feature. Returns false when called on a Feature struct with a different
    // address than the first one it saw for that feature name. Used only from
    // DCHECKs and tests.
    bool CheckFeatureIdentity(const Feature& feature);

    // Map from feature name to an OverrideEntry struct for the feature, if it
    // exists.
    std::map<std::string, OverrideEntry> overrides_;

    // Locked map that keeps track of seen features, to ensure a single feature is
    // only defined once. This verification is only done in builds with DCHECKs
    // enabled.
    Lock feature_identity_tracker_lock_;
    std::map<std::string, const Feature*> feature_identity_tracker_;

    // Whether this object has been fully initialized. This gets set to true as a
    // result of FinalizeInitialization().
    bool initialized_ = false;

    // Whether this object has been initialized from command line.
    bool initialized_from_command_line_ = false;

    DISALLOW_COPY_AND_ASSIGN(FeatureList);
};

} // namespace base

#endif // BASE_FEATURE_LIST_H_
